<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">


<!-- remove old header -->


<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /><title>cogen API Reference Documentation
        - Module: events</title><meta name="MSSmartTagsPreventParsing" content="true" /><meta http-equiv="imagetoolbar" content="no" /><link href="css/default.css" rel="stylesheet" type="text/css" /><link href="css/pygments.css" rel="stylesheet" type="text/css" />
    <!-- <link rel="shortcut icon" href="/images/favicon.ico" type="image/vnd.microsoft.icon"/> -->
    <link rel="stylesheet" href="css/apydia.css" type="text/css" />
    <script src="js/jquery-1.2.1.pack.js" type="text/javascript"></script>
    <script src="js/apydia.js" type="text/javascript"></script>
	<link rel="icon" href="images/favicon.ico" type="image/x-icon" />
</head>
<body>
    <div id="page">
        <div id="browser">
            <div class="browser-section">
                <h2>Module Index</h2>
                <ul>
                    <li>
                        <a href="cogen.html">cogen</a>
                    </li><li>
                        <a href="cogen.common.html">cogen.common</a>
                    </li><li>
                        <a href="cogen.core.html">cogen.core</a>
                    </li><li>
                        <a href="cogen.core.coroutines.html">cogen.core.coroutines</a>
                    </li><li class="active">
                        <a href="cogen.core.events.html">cogen.core.events</a>
                    </li><li>
                        <a href="cogen.core.pubsub.html">cogen.core.pubsub</a>
                    </li><li>
                        <a href="cogen.core.queue.html">cogen.core.queue</a>
                    </li><li>
                        <a href="cogen.core.reactors.html">cogen.core.reactors</a>
                    </li><li>
                        <a href="cogen.core.reactors.base.html">cogen.core.reactors.base</a>
                    </li><li>
                        <a href="cogen.core.reactors.iocp_proactor.html">cogen.core.reactors.iocp_proactor</a>
                    </li><li>
                        <a href="cogen.core.reactors.poll_reactor.html">cogen.core.reactors.poll_reactor</a>
                    </li><li>
                        <a href="cogen.core.reactors.qt_reactor.html">cogen.core.reactors.qt_reactor</a>
                    </li><li>
                        <a href="cogen.core.reactors.select_reactor.html">cogen.core.reactors.select_reactor</a>
                    </li><li>
                        <a href="cogen.core.schedulers.html">cogen.core.schedulers</a>
                    </li><li>
                        <a href="cogen.core.sockets.html">cogen.core.sockets</a>
                    </li><li>
                        <a href="cogen.core.util.html">cogen.core.util</a>
                    </li><li>
                        <a href="cogen.web.html">cogen.web</a>
                    </li><li>
                        <a href="cogen.web.async.html">cogen.web.async</a>
                    </li><li>
                        <a href="cogen.web.wsgi.html">cogen.web.wsgi</a>
                    </li>
                </ul>
            </div>
            <div class="browser-section">
                <h2>Classes</h2>
                <ul>
                    <li>
                        <a href="cogen.core.events.AddCoro.html">AddCoro</a>
                    </li><li>
                        <a href="cogen.core.events.ConnectionClosed.html">ConnectionClosed</a>
                    </li><li>
                        <a href="cogen.core.events.ConnectionError.html">ConnectionError</a>
                    </li><li>
                        <a href="cogen.core.events.CoroutineException.html">CoroutineException</a>
                    </li><li>
                        <a href="cogen.core.events.Join.html">Join</a>
                    </li><li>
                        <a href="cogen.core.events.OldCall.html">OldCall</a>
                    </li><li>
                        <a href="cogen.core.events.Operation.html">Operation</a>
                    </li><li>
                        <a href="cogen.core.events.OperationTimeout.html">OperationTimeout</a>
                    </li><li>
                        <a href="cogen.core.events.Signal.html">Signal</a>
                    </li><li>
                        <a href="cogen.core.events.Sleep.html">Sleep</a>
                    </li><li>
                        <a href="cogen.core.events.TimedOperation.html">TimedOperation</a>
                    </li><li>
                        <a href="cogen.core.events.WaitForSignal.html">WaitForSignal</a>
                    </li>
                </ul>
            </div>
            <div class="browser-section">
                <h2>Functions</h2>
                <ul>
                    <li>
                        <a href="cogen.core.events.html#function-Call">Call</a>
                    </li>
                </ul>
            </div>
        </div>
        <div id="content">
    <h1>Module:
        cogen.core.events
    </h1>
    <div class="docstring rst"><p>Base events (coroutine operations) and coroutine exceptions.</p>
</div>
    <ul class="link-bar">
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/core/events.py#1">View source</a>
    </li>
</ul>
    <div>
        <h2>Classes</h2>
            <h3>
                <a href="cogen.core.events.AddCoro.html">AddCoro</a>
            </h3>
            <div class="docstring rst"><p>A operation for adding a coroutine in the scheduler.</p>
<p>Example:</p>
<div class="source"><pre><span class="k">yield</span> <span class="n">events</span><span class="o">.</span><span class="n">AddCoro</span><span class="p">(</span><span class="n">some_coro</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(),</span> <span class="n">kwargs</span><span class="o">=</span><span class="p">{})</span>
</pre></div>
<p>This is similar to Call, but it doesn't pause the current coroutine.
See: <a class="reference" href="cogen.core.events.Operation.html">Operation</a>.</p>
</div>
            <ul class="link-bar">
    <li>
        <a href="cogen.core.events.AddCoro.html">Details</a>
    </li>
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/core/events.py#330">View source</a>
    </li>
</ul>
            <h3>
                <a href="cogen.core.events.ConnectionClosed.html">ConnectionClosed</a>
            </h3>
            <div class="docstring rst"><p>Raised when the other peer has closed connection.</p>
</div>
            <ul class="link-bar">
    <li>
        <a href="cogen.core.events.ConnectionClosed.html">Details</a>
    </li>
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/core/events.py#27">View source</a>
    </li>
</ul>
            <h3>
                <a href="cogen.core.events.ConnectionError.html">ConnectionError</a>
            </h3>
            <div class="docstring rst"><p>Raised when a socket has a error flag (in epoll or select)</p>
</div>
            <ul class="link-bar">
    <li>
        <a href="cogen.core.events.ConnectionError.html">Details</a>
    </li>
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/core/events.py#24">View source</a>
    </li>
</ul>
            <h3>
                <a href="cogen.core.events.CoroutineException.html">CoroutineException</a>
            </h3>
            <div class="docstring rst"><p>This is used intenally to carry exception state in the poller and
scheduler.</p>
</div>
            <ul class="link-bar">
    <li>
        <a href="cogen.core.events.CoroutineException.html">Details</a>
    </li>
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/core/events.py#17">View source</a>
    </li>
</ul>
            <h3>
                <a href="cogen.core.events.Join.html">Join</a>
            </h3>
            <div class="docstring rst"><p>A operation for waiting on a coroutine.</p>
<p>Example:</p>
<div class="source"><pre><span class="nd">@coroutine</span>
<span class="k">def</span> <span class="nf">coro_a</span><span class="p">():</span>
    <span class="n">return_value</span> <span class="o">=</span> <span class="k">yield</span> <span class="n">events</span><span class="o">.</span><span class="n">Join</span><span class="p">(</span><span class="n">ref</span><span class="p">)</span>


<span class="nd">@coroutine</span>
<span class="k">def</span> <span class="nf">coro_b</span><span class="p">():</span>
    <span class="k">yield</span> <span class="s">"bla"</span>
    <span class="k">raise</span> <span class="ne">StopIteration</span><span class="p">(</span><span class="s">"some return value"</span><span class="p">)</span>

<span class="n">ref</span> <span class="o">=</span> <span class="n">scheduler</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">coro_b</span><span class="p">)</span>
<span class="n">scheduler</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">coro_a</span><span class="p">)</span>
</pre></div>
<p>This will pause the coroutine and resume it when the other coroutine
(<cite>ref</cite> in the example) has died.</p>
</div>
            <ul class="link-bar">
    <li>
        <a href="cogen.core.events.Join.html">Details</a>
    </li>
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/core/events.py#373">View source</a>
    </li>
</ul>
            <h3>
                <a href="cogen.core.events.OldCall.html">OldCall</a>
            </h3>
            <div class="docstring rst"><p>This will pause the current coroutine, add a new coro in the scheduler and
resume the callee when it returns.</p>
<p>Usage:</p>
<div class="source"><pre><span class="n">result</span> <span class="o">=</span> <span class="k">yield</span> <span class="n">events</span><span class="o">.</span><span class="n">Call</span><span class="p">(</span><span class="n">mycoro</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(),</span> <span class="n">kwargs</span><span class="o">=</span><span class="p">{},</span> <span class="n">prio</span><span class="o">=</span><span class="n">priority</span><span class="o">.</span><span class="n">DEFAULT</span><span class="p">)</span>
</pre></div>
<ul class="simple">
<li>mycoro - the coroutine to add.</li>
<li>args, kwargs - params to call the coroutine with</li>
<li>if <cite>prio</cite> is set the new coroutine will be added in the top of the
scheduler queue</li>
</ul>
<p>See: <a class="reference" href="cogen.core.events.Operation.html">Operation</a>.</p>
</div>
            <ul class="link-bar">
    <li>
        <a href="cogen.core.events.OldCall.html">Details</a>
    </li>
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/core/events.py#284">View source</a>
    </li>
</ul>
            <h3>
                <a href="cogen.core.events.Operation.html">Operation</a>
            </h3>
            <div class="docstring rst"><p>All operations derive from this. This base class handles
the priority flag.</p>
<p>Eg:</p>
<div class="source"><pre><span class="k">yield</span> <span class="n">Operation</span><span class="p">(</span><span class="n">prio</span><span class="o">=</span><span class="n">priority</span><span class="o">.</span><span class="n">DEFAULT</span><span class="p">)</span>
</pre></div>
<ul class="simple">
<li>prio - a priority constant, where the coro is appended on the active
coroutine queue and how the coroutine is runned depend on this.</li>
</ul>
<p>If you need something that can't be done in a coroutine fashion you
probabily need to subclass this and make a custom operation for your
issue.</p>
<p>Note: you don't really use this, this is for subclassing for other operations.</p>
</div>
            <ul class="link-bar">
    <li>
        <a href="cogen.core.events.Operation.html">Details</a>
    </li>
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/core/events.py#35">View source</a>
    </li>
</ul>
            <h3>
                <a href="cogen.core.events.OperationTimeout.html">OperationTimeout</a>
            </h3>
            <div class="docstring rst"><p>Raised when the timeout for a operation expires. The exception
message will be the operation</p>
</div>
            <ul class="link-bar">
    <li>
        <a href="cogen.core.events.OperationTimeout.html">Details</a>
    </li>
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/core/events.py#30">View source</a>
    </li>
</ul>
            <h3>
                <a href="cogen.core.events.Signal.html">Signal</a>
            </h3>
            <div class="docstring rst"><p>This will resume the coroutines that where paused with WaitForSignal.</p>
<p>Usage:</p>
<div class="source"><pre><span class="n">nr</span> <span class="o">=</span> <span class="k">yield</span> <span class="n">events</span><span class="o">.</span><span class="n">Signal</span><span class="p">(</span>
    <span class="n">name</span><span class="p">,</span>
    <span class="n">value</span><span class="p">,</span>
    <span class="n">prio</span><span class="o">=</span><span class="n">priority</span><span class="o">.</span><span class="n">DEFAULT</span>
<span class="p">)</span>
</pre></div>
<ul class="simple">
<li>nr - the number of coroutines woken up</li>
<li>name - object that coroutines wait on, can be a string</li>
<li>value - object that the waiting coros recieve when they are resumed.</li>
</ul>
<p>See: <a class="reference" href="cogen.core.events.Operation.html">Operation</a>.</p>
</div>
            <ul class="link-bar">
    <li>
        <a href="cogen.core.events.Signal.html">Details</a>
    </li>
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/core/events.py#207">View source</a>
    </li>
</ul>
            <h3>
                <a href="cogen.core.events.Sleep.html">Sleep</a>
            </h3>
            <div class="docstring rst"><p>A operation to pausing the coroutine for a specified amount of time.</p>
<p>Usage:</p>
<div class="source"><pre><span class="k">yield</span> <span class="n">events</span><span class="o">.</span><span class="n">Sleep</span><span class="p">(</span><span class="n">time_object</span><span class="p">)</span>
</pre></div>
<ul class="simple">
<li>time_object - a datetime or timedelta object, or a number of seconds</li>
</ul>
<div class="source"><pre><span class="k">yield</span> <span class="n">events</span><span class="o">.</span><span class="n">Sleep</span><span class="p">(</span><span class="n">timestamp</span><span class="o">=</span><span class="n">ts</span><span class="p">)</span>
</pre></div>
<ul class="simple">
<li>ts - a timestamp</li>
</ul>
</div>
            <ul class="link-bar">
    <li>
        <a href="cogen.core.events.Sleep.html">Details</a>
    </li>
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/core/events.py#422">View source</a>
    </li>
</ul>
            <h3>
                <a href="cogen.core.events.TimedOperation.html">TimedOperation</a>
            </h3>
            <div class="docstring rst"><p>Operations that have a timeout derive from this.</p>
<p>Eg:</p>
<div class="source"><pre><span class="k">yield</span> <span class="n">TimedOperation</span><span class="p">(</span>
    <span class="n">timeout</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    <span class="n">weak_timeout</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span>
    <span class="n">prio</span><span class="o">=</span><span class="n">priority</span><span class="o">.</span><span class="n">DEFAULT</span>
<span class="p">)</span>
</pre></div>
<ul class="simple">
<li>timeout - can be a float/int (number of seconds) or a timedelta or a datetime value
if it's a datetime the timeout will occur on that moment</li>
<li>weak_timeout - strong timeouts just happen when specified, weak_timeouts
get delayed if some action happens (eg: new but not enough data recieved)</li>
</ul>
<p>See: <a class="reference" href="cogen.core.events.Operation.html">Operation</a>.
Note: you don't really use this, this is for subclassing for other operations.</p>
</div>
            <ul class="link-bar">
    <li>
        <a href="cogen.core.events.TimedOperation.html">Details</a>
    </li>
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/core/events.py#79">View source</a>
    </li>
</ul>
            <h3>
                <a href="cogen.core.events.WaitForSignal.html">WaitForSignal</a>
            </h3>
            <div class="docstring rst"><p>The coroutine will resume when the same object is Signaled.</p>
<p>Eg:</p>
<div class="source"><pre><span class="n">value</span> <span class="o">=</span> <span class="k">yield</span> <span class="n">events</span><span class="o">.</span><span class="n">WaitForSignal</span><span class="p">(</span>
    <span class="n">name</span><span class="p">,</span>
    <span class="n">timeout</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    <span class="n">weak_timeout</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span>
    <span class="n">prio</span><span class="o">=</span><span class="n">priority</span><span class="o">.</span><span class="n">DEFAULT</span>
<span class="p">)</span>
</pre></div>
<ul class="simple">
<li>name - a object to wait on, can use strings for this - string used to
wait is equal to the string used to signal.</li>
<li>value - a object sent with the signal.
See: <a class="reference" href="cogen.core.events.Signal.html">Signal</a></li>
</ul>
<p>See: <a class="reference" href="cogen.core.events.TimedOperation.html">TimedOperation</a>.</p>
</div>
            <ul class="link-bar">
    <li>
        <a href="cogen.core.events.WaitForSignal.html">Details</a>
    </li>
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/core/events.py#145">View source</a>
    </li>
</ul>
    </div>
    <div>
        <h2>Functions</h2>
            <h3 id="function-Call">
                Call
                <span class="args">(coro, args=None, kwargs=None, **kws)</span>
            </h3>
            <div class="docstring rst"><p>You don't need to use this. You can just yield the called coroutine:</p>
<div class="source"><pre><span class="n">result</span> <span class="o">=</span> <span class="k">yield</span> <span class="n">mycoro</span><span class="p">(</span> <span class="p">[</span><span class="n">arguments</span><span class="p">]</span> <span class="p">)</span>
</pre></div>
<p>Compared to <a class="reference" href="cogen.core.events.OldCall.html">OldCall</a>,
instead of returning an Operation object it returns the
new Coroutine directly that will act as a Call operation in it's pre-init
state. This is faster for 2 reasons: avoids one Operation instatiation and
avoids pushing and poping the new coroutine on the active coros queue.</p>
</div>
            <ul class="link-bar">
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/core/events.py#266">View source</a>
    </li>
</ul>
    </div>
        </div>
        <div id="footer">
            Generated with <a href="http://apydia.ematia.de/" class="extern">
            Apydia 0.0.3</a>
        </div>
    </div>
</body>
</html>